# ESP-IDF Components library

[![Build Status](https://github.com/UncleRus/esp-idf-lib/workflows/Build%20examples/badge.svg)](https://github.com/UncleRus/esp-idf-lib/actions?query=workflow%3A%22Build+examples%22)
[![Build the documentation](https://github.com/UncleRus/esp-idf-lib/workflows/Build%20the%20documentation/badge.svg)](https://github.com/UncleRus/esp-idf-lib/actions?query=workflow%3A%22Build+the+documentation%22)
[![Docs Status](https://readthedocs.org/projects/esp-idf-lib/badge/?version=latest&style=flat)](https://esp-idf-lib.readthedocs.io/en/latest/)

Components for Espressif ESP32 [ESP-IDF framework](https://github.com/espressif/esp-idf)
and [ESP8266 RTOS SDK](https://github.com/espressif/ESP8266_RTOS_SDK).

Part of them ported from [esp-open-rtos](https://github.com/SuperHouse/esp-open-rtos).

## Supported versions of frameworks and devices

| Chip           | Framework          | Versions
|----------------|--------------------|-----------------------
| ESP32          | ESP-IDF            | master, v4.x, v.3.3.5
| ESP32-S2 *[1]* | ESP-IDF            | master, v4.x, v.3.3.5
| ESP32-C3 *[1]* | ESP-IDF            | master, v4.x, v.3.3.5
| ESP8266  *[2]* | ESP8266 RTOS SDK   | master, v3.3

[1] *Use "`idf.py set-target esp32s2`" or "`idf.py set-target esp32c3`" before "`idf.py menuconfig`" to change
the chip type.*

[2] *Due to the incompatibility of ESP8266 drivers and hardware, some
libraries are not* *supported on ESP8266 (see "ESP8266" column in the tables).*

## How to use

### ESP32

Clone this repository somewhere, e.g.:

```Shell
cd ~/myprojects/esp
git clone https://github.com/UncleRus/esp-idf-lib.git
```

Add path to components in your [project makefile](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system-legacy.html),
e.g:

```Makefile
PROJECT_NAME := my-esp-project
EXTRA_COMPONENT_DIRS := /home/user/myprojects/esp/esp-idf-lib/components
include $(IDF_PATH)/make/project.mk
```

or in [CMakeLists.txt](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html):

```CMake
cmake_minimum_required(VERSION 3.5)
set(EXTRA_COMPONENT_DIRS /home/user/myprojects/esp/esp-idf-lib/components)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my-esp-project)
```

or with CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html)

```CMake
cmake_minimum_required(VERSION 3.11)
include(FetchContent)
FetchContent_Declare(
  espidflib
  GIT_REPOSITORY https://github.com/UncleRus/esp-idf-lib.git
)
FetchContent_MakeAvailable(espidflib)
set(EXTRA_COMPONENT_DIRS ${espidflib_SOURCE_DIR}/components)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my-esp-project)
```

### ESP8266 RTOS SDK

Clone this repository somewhere, e.g.:

```Shell
cd ~/myprojects/esp
git clone https://github.com/UncleRus/esp-idf-lib.git
```

Add path to components in your [project makefile](https://docs.espressif.com/projects/esp8266-rtos-sdk/en/latest/api-guides/build-system.html),
e.g:

```Makefile
PROJECT_NAME := my-esp-project
EXTRA_COMPONENT_DIRS := /home/user/myprojects/esp/esp-idf-lib/components
EXCLUDE_COMPONENTS := max7219 mcp23x17 led_strip max31865
include $(IDF_PATH)/make/project.mk
```

See [GitHub examples](https://github.com/UncleRus/esp-idf-lib/tree/master/examples)
or [GitLab examples](https://gitlab.com/UncleRus/esp-idf-lib/tree/master/examples).

## Documentation

- [Documentation](https://esp-idf-lib.readthedocs.io/en/latest/)
- [Frequently asked questions](FAQ.md)

## Components
<% groups.sort_by!(&:description).each do |g| %>
### <%= g.description %>

| Component                | Description                                                                      | License | Supported on       | Thread safety
|--------------------------|----------------------------------------------------------------------------------|---------|--------------------|--------------
<%
    components = all_components.select { |c| c.group_of?(g.name) }.sort_by!(&:name).each do |c|
      name = format("%-24s", "**#{c.name}**")
      description = format("%-80s", c.description)
      licenses = format("%-7s", c.licenses.map(&:name).join(", "))
      supported_on = format("%-18s", c.targets.map { |t| "`#{t.name}`" }.join(", "))
-%>
| <%= name %> | <%= description %> | <%= licenses %> | <%= supported_on %> | <%= c.thread_safe ? "Yes" : "No" %>
<%   end -%>
<% end -%>

## Library maintainers

- [Ruslan V. Uss](https://github.com/UncleRus)
- [Tomoyuki Sakurai](https://github.com/trombik)

## Credits

- [Tomoyuki Sakurai](https://github.com/trombik), developer of the LM75 and
  SK9822/APA102 drivers, author of the RTOS SDK ESP82666 support, master CI
- [Gunar Schorcht](https://github.com/gschorcht), developer of SHT3x, BME680
  and CCS811 drivers
- [Brian Schwind](https://github.com/bschwind), developer of TS2561 and
  TSL4531 drivers
- [Andrej Krutak](https://github.com/andree182), developer of BH1750 driver
- Frank Bargstedt, developer of BMP180 driver
- [sheinz](https://github.com/sheinz), developer of BMP280 driver
- [Jonathan Hartsuiker](https://github.com/jsuiker), developer of DHT driver
- [Grzegorz Hetman](https://github.com/hetii), developer of DS18B20 driver
- [Alex Stewart](https://github.com/astewart-consensus), developer of DS18B20 driver
- [Richard A Burton](mailto:richardaburton@gmail.com), developer of DS3231 driver
- [Bhuvanchandra DV](https://github.com/bhuvanchandra), developer of DS3231 driver
- [Zaltora](https://github.com/Zaltora), developer of INA3231 driver
- [Bernhard Guillon](https://gitlab.com/mrnice), developer of MS5611-01BA03 driver
- [Pham Ngoc Thanh](https://github.com/panoti), developer of PCF8591 driver
- [Lucio Tarantino](https://github.com/dianlight), developer of ADS111x driver
- [Julian Dörner](https://github.com/juliandoerner), developer of TSL2591 driver
- [FastLED community](https://github.com/FastLED), developers of `lib8tion`,
  `color` and `noise` libraries
- [Erriez](https://github.com/Erriez), developer of MH-Z19B driver
- [David Douard](https://github.com/douardda), developer of MH-Z19B driver
- [Nate Usher](https://github.com/nated0g), developer of SCD30 driver
